isvalid()

Hierarchies

focus()

Set the input focus to the control (if applicable). If the control is able to set the input focus, this method sets the focus and returns true.
If input focus is not applicable for the control (e.g. a label or an image etc.) then the method should return false

e.g.

if ( $input.is(":visible") ) {
  $input.focus();
  return true;
}
return false;

jQuery Plugin Notes

jQuery chaining is not required by xrui controls and so it's not required to return the jQuery object from any methods (although it's good practice to do so).

Convention is also to implement a destroy method to free the data associated with the control.

Non-Input Controls

If a control is not designed to capture data (e.g. Label, Image etc) then the isvalid and focus methods are not required to be implemented. See xrui-label.js for more details.

Control Containers

Controls can also contain other controls (e.g. tabsheets, columns). In this situation, the plugin should implement the getSubCtrlLists() method.
This method returns a list of control sets (e.g. individual tab pages or columns).
For more information see xrui-columns.js, xrui-tabsheet.js or xrui-panels.js

Useful Dialog Methods (Helpers)

There are several dialog methods which are useful for the control author...

renderHelp(controlJqueryObject,knowledgeObject)
This method takes the knowledge object and (if it's "help" object control property is set) displays a popup help to the right of the control. In practice, the call from the plugin would look something like this...
data.definition.dialog.renderHelp($this,data.kb);

Dialog Actions

Certain controls require the dialog to perform an action (e.g. an OK button). These are achieved with methods of the dialog object in the definition object.

e.g.

// Attempt to leave the dialog (assuming all controls are valid)
data.definition.dialog.ok();

More Useful Dialog Methods

// Attempt to leave dialog
ok (<bypass exit proc?>);
// Go back to previous dialog
back ();
// Exit the entire session
exit (<perform exit check?>);
// Execute a macro procedure
macro(<macro procedure ID> , <perform ok when complete?>);

For more information see xrui-button.js.

Caption or Static String Expansion

In knowledge builder, most captions are allowed to have "embedded objects" which are contained in braces (e.g. "The result of the decision is {decision_result}"). To process these, the expandEmbedded(captionText) dialog function should be used.

e.g.

var txt = aCntrl.dialog.expandEmbedded(aCntrl.caption);
$this.innerHtml(txt);

Integration into the XpertRule design environment

By placing your plugin in the "Deployment Plugins" folder, Xpertrule will extend the Knowledge Builder form designer to allow users to use your new control. The control will appear on the toolbar in the same way as an existing internal control. The icon used to represent the control is specified in the Plugin XML Definition which should be at the top of your plugin file. This is also where you define any editor properties which your control required.

Plugin XML Definition

At the top of your plugin file, in the comments, you should include an XML message which tells XpertRule knowledge builder about important aspects of your new control. An example message might look like this...

<xrui name="map" icon="icon.png" desktop="true" mobile="false">
  <_include type="js" src="http://maps.googleapis.com/maps/api/js?key=<YOUR KEY HERE>&sensor=true" />
  <postcode type="tied" typeaccept="text" />
  <zoom type="int" value="8" />
  <bkgndColor type="color" value="#000080" />
  <msize type="enum" values="small,medium,large" />
</xrui>

There are 3 distinct aspects to the definition.

• xrui attributes

  <xrui name="map" icon="icon.png" desktop="true" mobile="false">

  The name attribute is the name which knowledge builder will use for your plugin. It is used in various places in the dialog editor and used to reference the xrui_<control name> plugin (defined at the bottom of your plugin file).
  The icon is the name of a png file which should be placed in your plugin folder. This is used as the image on the dialog editor toolbar.
  The desktop and mobile attributes specify whether the plugin supports desktop and/or mobile XpertRule dialogs.

• Control properties

  <postcode type="tied" typeaccept="text" />
  <zoom type="int" value="8" />
  <bkgndColor type="color" value="#000080" />
  <msize type="enum" values="small,medium,large" />

  These are custom properties associated with your control. They will show in the property editor in knowledge builder and are available in your plugin in the definition object. The type attribute specifies the type of the property (see table below). The value attribute is the default value for this property when the user first includes it on a dialog.

  Valid property types :

Additional attributes :

Control Properties in Form Rules :
If you implement the following properties (by name), they will automatically be included in the XpertRule Dialog Form Rule Editor.

• Static Includes

  <_include type="js" src="http://maps.googleapis.com/maps/api/js?key=<YOUR KEY HERE>&sensor=true" />

By default, all js and css files in the plugin folder are automatically included at execution time. Sometimes, you may need to reference external files (e.g. the google maps api). This is achieved with the _include tag. The type attribute can be either "js" or "css".